<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>Miscellaneous &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="NumPy User Guide" href="index.html" >
    <link rel="next" title="NumPy for Matlab users" href="numpy-for-matlab-users.html" >
    <link rel="prev" title="Subclassing ndarray" href="basics.subclassing.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" accesskey="U">NumPy User Guide</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="numpy-for-matlab-users.html" title="NumPy for Matlab users"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="basics.subclassing.html" title="Subclassing ndarray"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Miscellaneous</a><ul>
<li><a class="reference internal" href="#ieee-754-floating-point-special-values">IEEE 754 Floating Point Special Values</a></li>
<li><a class="reference internal" href="#how-numpy-handles-numerical-exceptions">How numpy handles numerical exceptions</a></li>
<li><a class="reference internal" href="#examples">Examples</a></li>
<li><a class="reference internal" href="#interfacing-to-c">Interfacing to C</a></li>
<li><a class="reference internal" href="#interfacing-to-fortran">Interfacing to Fortran:</a></li>
<li><a class="reference internal" href="#id1">Interfacing to C++:</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="basics.subclassing.html"
                        title="previous chapter">Subclassing ndarray</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="numpy-for-matlab-users.html"
                        title="next chapter">NumPy for Matlab users</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="module-numpy.doc.misc">
<span id="miscellaneous"></span><h1>Miscellaneous<a class="headerlink" href="#module-numpy.doc.misc" title="Permalink to this headline">¶</a></h1>
<div class="section" id="ieee-754-floating-point-special-values">
<h2>IEEE 754 Floating Point Special Values<a class="headerlink" href="#ieee-754-floating-point-special-values" title="Permalink to this headline">¶</a></h2>
<p>Special values defined in numpy: nan, inf,</p>
<p>NaNs can be used as a poor-man’s mask (if you don’t care what the
original value was)</p>
<p>Note: cannot use equality to test NaNs. E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">myarr</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.</span><span class="p">,</span> <span class="mf">0.</span><span class="p">,</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span><span class="p">,</span> <span class="mf">3.</span><span class="p">])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">nonzero</span><span class="p">(</span><span class="n">myarr</span> <span class="o">==</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span><span class="p">)</span>
<span class="go">(array([], dtype=int64),)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">nan</span> <span class="o">==</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span>  <span class="c1"># is always False! Use special numpy functions instead.</span>
<span class="go">False</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">myarr</span><span class="p">[</span><span class="n">myarr</span> <span class="o">==</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span><span class="p">]</span> <span class="o">=</span> <span class="mf">0.</span> <span class="c1"># doesn&#39;t work</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">myarr</span>
<span class="go">array([  1.,   0.,  NaN,   3.])</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">myarr</span><span class="p">[</span><span class="n">np</span><span class="o">.</span><span class="n">isnan</span><span class="p">(</span><span class="n">myarr</span><span class="p">)]</span> <span class="o">=</span> <span class="mf">0.</span> <span class="c1"># use this instead find</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">myarr</span>
<span class="go">array([ 1.,  0.,  0.,  3.])</span>
</pre></div>
</div>
<p>Other related special value functions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">isinf</span><span class="p">():</span>    <span class="kc">True</span> <span class="k">if</span> <span class="n">value</span> <span class="ow">is</span> <span class="n">inf</span>
<span class="n">isfinite</span><span class="p">():</span> <span class="kc">True</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">nan</span> <span class="ow">or</span> <span class="n">inf</span>
<span class="n">nan_to_num</span><span class="p">():</span> <span class="n">Map</span> <span class="n">nan</span> <span class="n">to</span> <span class="mi">0</span><span class="p">,</span> <span class="n">inf</span> <span class="n">to</span> <span class="nb">max</span> <span class="nb">float</span><span class="p">,</span> <span class="o">-</span><span class="n">inf</span> <span class="n">to</span> <span class="nb">min</span> <span class="nb">float</span>
</pre></div>
</div>
<p>The following corresponds to the usual functions except that nans are excluded
from the results:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nansum</span><span class="p">()</span>
<span class="n">nanmax</span><span class="p">()</span>
<span class="n">nanmin</span><span class="p">()</span>
<span class="n">nanargmax</span><span class="p">()</span>
<span class="n">nanargmin</span><span class="p">()</span>

<span class="o">&gt;&gt;&gt;</span> <span class="n">x</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">arange</span><span class="p">(</span><span class="mf">10.</span><span class="p">)</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">x</span><span class="p">[</span><span class="mi">3</span><span class="p">]</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">nan</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">x</span><span class="o">.</span><span class="n">sum</span><span class="p">()</span>
<span class="n">nan</span>
<span class="o">&gt;&gt;&gt;</span> <span class="n">np</span><span class="o">.</span><span class="n">nansum</span><span class="p">(</span><span class="n">x</span><span class="p">)</span>
<span class="mf">42.0</span>
</pre></div>
</div>
</div>
<div class="section" id="how-numpy-handles-numerical-exceptions">
<h2>How numpy handles numerical exceptions<a class="headerlink" href="#how-numpy-handles-numerical-exceptions" title="Permalink to this headline">¶</a></h2>
<p>The default is to <code class="docutils literal notranslate"><span class="pre">'warn'</span></code> for <code class="docutils literal notranslate"><span class="pre">invalid</span></code>, <code class="docutils literal notranslate"><span class="pre">divide</span></code>, and <code class="docutils literal notranslate"><span class="pre">overflow</span></code>
and <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code> for <code class="docutils literal notranslate"><span class="pre">underflow</span></code>.  But this can be changed, and it can be
set individually for different kinds of exceptions. The different behaviors
are:</p>
<blockquote>
<div><ul class="simple">
<li><p>‘ignore’ : Take no action when the exception occurs.</p></li>
<li><p>‘warn’   : Print a <em class="xref py py-obj">RuntimeWarning</em> (via the Python <a class="reference external" href="https://docs.python.org/dev/library/warnings.html#module-warnings" title="(in Python v3.9)"><code class="xref py py-obj docutils literal notranslate"><span class="pre">warnings</span></code></a> module).</p></li>
<li><p>‘raise’  : Raise a <em class="xref py py-obj">FloatingPointError</em>.</p></li>
<li><p>‘call’   : Call a function specified using the <em class="xref py py-obj">seterrcall</em> function.</p></li>
<li><p>‘print’  : Print a warning directly to <code class="docutils literal notranslate"><span class="pre">stdout</span></code>.</p></li>
<li><p>‘log’    : Record error in a Log object specified by <em class="xref py py-obj">seterrcall</em>.</p></li>
</ul>
</div></blockquote>
<p>These behaviors can be set for all kinds of errors or specific ones:</p>
<blockquote>
<div><ul class="simple">
<li><p>all       : apply to all numeric exceptions</p></li>
<li><p>invalid   : when NaNs are generated</p></li>
<li><p>divide    : divide by zero (for integers as well!)</p></li>
<li><p>overflow  : floating point overflows</p></li>
<li><p>underflow : floating point underflows</p></li>
</ul>
</div></blockquote>
<p>Note that integer divide-by-zero is handled by the same machinery.
These behaviors are set on a per-thread basis.</p>
</div>
<div class="section" id="examples">
<h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">oldsettings</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">seterr</span><span class="p">(</span><span class="nb">all</span><span class="o">=</span><span class="s1">&#39;warn&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="n">dtype</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">float32</span><span class="p">)</span><span class="o">/</span><span class="mf">0.</span>
<span class="go">invalid value encountered in divide</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">j</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">seterr</span><span class="p">(</span><span class="n">under</span><span class="o">=</span><span class="s1">&#39;ignore&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="mf">1.e-100</span><span class="p">])</span><span class="o">**</span><span class="mi">10</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">j</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">seterr</span><span class="p">(</span><span class="n">invalid</span><span class="o">=</span><span class="s1">&#39;raise&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">sqrt</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">array</span><span class="p">([</span><span class="o">-</span><span class="mf">1.</span><span class="p">]))</span>
<span class="go">FloatingPointError: invalid value encountered in sqrt</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">errorhandler</span><span class="p">(</span><span class="n">errstr</span><span class="p">,</span> <span class="n">errflag</span><span class="p">):</span>
<span class="gp">... </span>     <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;saw stupid error!&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">seterrcall</span><span class="p">(</span><span class="n">errorhandler</span><span class="p">)</span>
<span class="go">&lt;function err_handler at 0x...&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">j</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">seterr</span><span class="p">(</span><span class="nb">all</span><span class="o">=</span><span class="s1">&#39;call&#39;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">np</span><span class="o">.</span><span class="n">zeros</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="n">dtype</span><span class="o">=</span><span class="n">np</span><span class="o">.</span><span class="n">int32</span><span class="p">)</span><span class="o">/</span><span class="mi">0</span>
<span class="go">FloatingPointError: invalid value encountered in divide</span>
<span class="go">saw stupid error!</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">j</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">seterr</span><span class="p">(</span><span class="o">**</span><span class="n">oldsettings</span><span class="p">)</span> <span class="c1"># restore previous</span>
<span class="gp">... </span>                             <span class="c1"># error-handling settings</span>
</pre></div>
</div>
</div>
<div class="section" id="interfacing-to-c">
<h2>Interfacing to C<a class="headerlink" href="#interfacing-to-c" title="Permalink to this headline">¶</a></h2>
<p>Only a survey of the choices. Little detail on how each works.</p>
<ol class="arabic simple">
<li><p>Bare metal, wrap your own C-code manually.</p></li>
</ol>
<blockquote>
<div><ul class="simple">
<li><p>Plusses:</p>
<ul>
<li><p>Efficient</p></li>
<li><p>No dependencies on other tools</p></li>
</ul>
</li>
<li><p>Minuses:</p>
<ul>
<li><p>Lots of learning overhead:</p>
<ul>
<li><p>need to learn basics of Python C API</p></li>
<li><p>need to learn basics of numpy C API</p></li>
<li><p>need to learn how to handle reference counting and love it.</p></li>
</ul>
</li>
<li><p>Reference counting often difficult to get right.</p>
<ul>
<li><p>getting it wrong leads to memory leaks, and worse, segfaults</p></li>
</ul>
</li>
<li><p>API will change for Python 3.0!</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="2">
<li><p>Cython</p></li>
</ol>
<blockquote>
<div><ul class="simple">
<li><p>Plusses:</p>
<ul>
<li><p>avoid learning C API’s</p></li>
<li><p>no dealing with reference counting</p></li>
<li><p>can code in pseudo python and generate C code</p></li>
<li><p>can also interface to existing C code</p></li>
<li><p>should shield you from changes to Python C api</p></li>
<li><p>has become the de-facto standard within the scientific Python community</p></li>
<li><p>fast indexing support for arrays</p></li>
</ul>
</li>
<li><p>Minuses:</p>
<ul>
<li><p>Can write code in non-standard form which may become obsolete</p></li>
<li><p>Not as flexible as manual wrapping</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="3">
<li><p>ctypes</p></li>
</ol>
<blockquote>
<div><ul>
<li><p>Plusses:</p>
<ul>
<li><p>part of Python standard library</p></li>
<li><p>good for interfacing to existing sharable libraries, particularly
Windows DLLs</p></li>
<li><p>avoids API/reference counting issues</p></li>
<li><p>good numpy support: arrays have all these in their ctypes
attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">data</span>              <span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">get_strides</span>
<span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">data_as</span>           <span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">shape</span>
<span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">get_as_parameter</span>  <span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">shape_as</span>
<span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">get_data</span>          <span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">strides</span>
<span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">get_shape</span>         <span class="n">a</span><span class="o">.</span><span class="n">ctypes</span><span class="o">.</span><span class="n">strides_as</span>
</pre></div>
</div>
</li>
</ul>
</li>
<li><p>Minuses:</p>
<ul class="simple">
<li><p>can’t use for writing code to be turned into C extensions, only a wrapper
tool.</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="4">
<li><p>SWIG (automatic wrapper generator)</p></li>
</ol>
<blockquote>
<div><ul class="simple">
<li><p>Plusses:</p>
<ul>
<li><p>around a long time</p></li>
<li><p>multiple scripting language support</p></li>
<li><p>C++ support</p></li>
<li><p>Good for wrapping large (many functions) existing C libraries</p></li>
</ul>
</li>
<li><p>Minuses:</p>
<ul>
<li><p>generates lots of code between Python and the C code</p></li>
<li><p>can cause performance problems that are nearly impossible to optimize
out</p></li>
<li><p>interface files can be hard to write</p></li>
<li><p>doesn’t necessarily avoid reference counting issues or needing to know
API’s</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="5">
<li><p>scipy.weave</p></li>
</ol>
<blockquote>
<div><ul class="simple">
<li><p>Plusses:</p>
<ul>
<li><p>can turn many numpy expressions into C code</p></li>
<li><p>dynamic compiling and loading of generated C code</p></li>
<li><p>can embed pure C code in Python module and have weave extract, generate
interfaces and compile, etc.</p></li>
</ul>
</li>
<li><p>Minuses:</p>
<ul>
<li><p>Future very uncertain: it’s the only part of Scipy not ported to Python 3
and is effectively deprecated in favor of Cython.</p></li>
</ul>
</li>
</ul>
</div></blockquote>
<ol class="arabic simple" start="6">
<li><p>Psyco</p></li>
</ol>
<blockquote>
<div><ul class="simple">
<li><p>Plusses:</p>
<ul>
<li><p>Turns pure python into efficient machine code through jit-like
optimizations</p></li>
<li><p>very fast when it optimizes well</p></li>
</ul>
</li>
<li><p>Minuses:</p>
<ul>
<li><p>Only on intel (windows?)</p></li>
<li><p>Doesn’t do much for numpy?</p></li>
</ul>
</li>
</ul>
</div></blockquote>
</div>
<div class="section" id="interfacing-to-fortran">
<h2>Interfacing to Fortran:<a class="headerlink" href="#interfacing-to-fortran" title="Permalink to this headline">¶</a></h2>
<p>The clear choice to wrap Fortran code is
<a class="reference external" href="https://docs.scipy.org/doc/numpy/f2py/">f2py</a>.</p>
<p>Pyfort is an older alternative, but not supported any longer.
Fwrap is a newer project that looked promising but isn’t being developed any
longer.</p>
</div>
<div class="section" id="id1">
<h2>Interfacing to C++:<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<blockquote>
<div><ol class="arabic simple">
<li><p>Cython</p></li>
<li><p>CXX</p></li>
<li><p>Boost.python</p></li>
<li><p>SWIG</p></li>
<li><p>SIP (used mainly in PyQT)</p></li>
</ol>
</div></blockquote>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>